Once installed, everything BuildBetter does on your machine runs through a single binary: bb. It’s small, scriptable, and stays out of your way until you call it.
bb # show top-level helpbb <command> -h # show help for a specific commandbb --version # print the installed version
The CLI tracks every session you have with a supported coding agent (Claude Code, Codex, Cursor, etc.) and indexes it by repo · branch · commit · author. See the [Agent Sessions](/pages/BuildBetter SH/agent-sessions) page for the full story; here’s the command surface.
bb agent-sessions resume # interactive picker for the current branchbb agent-sessions resume <session-id> # resume a specific sessionbb agent-sessions list # sessions in this repobb agent-sessions list --branch <name> # filter by branchbb agent-sessions list --author <user> # filter by teammatebb agent-sessions list --since 7d # filter by time windowbb agent-sessions search "<query>" # full-text search across sessionsbb agent-sessions show <session-id> # print metadata + summary for one sessionbb agent-sessions link <pr-number> # attach the current session to a PRbb agent-sessions delete <session-id> # remove a single sessionbb agent-sessions purge --repo . # remove every session for this repo
Run bb agent-sessions resume from inside any git checkout. The CLI scopes the picker to the repo and branch you’re standing in, so the list is always short.
Skills are slash commands like /bb-specify and /trust-but-verify that get installed into your coding agent. They’re shipped as packs — see the [Skills reference](/pages/BuildBetter SH/skills) for what each one does.
bb skills install <pack> # install a pack (spec-workflow, testing, core)bb skills install --all # install every packbb skills uninstall <pack> # remove a packbb skills list # show installed packs and individual skillsbb skills update # pull the latest version of every installed packbb skills platforms # show which agents are detected and where skills go
bb login # browser-based sign-in to your free BuildBetter workspacebb logout # remove cached credentialsbb whoami # show the signed-in user and workspacebb sync # force a sync of local sessions to the cloudbb sync --status # show last sync time and pending items
You can use the CLI fully offline — bb login is optional. Without it, sessions stay on disk and only resume on the same machine.
bb doctor # check install, PATH, agent detection, sync healthbb doctor --fix # attempt to repair common issues (PATH, shell rc, perms)bb update # update the bb binary and every installed skill packbb uninstall # remove ~/.buildbetter/ and the binary
bb doctor is the first thing to run when something feels off. Sample output:
✓ bb 1.2.0 (latest)✓ ~/.buildbetter/bin in PATH✓ Signed in as spencer@buildbetter.app✓ Claude Code · skills installed at ~/.claude/skills✓ Codex CLI · skills installed at ~/.codex/skills⚠ Cursor · detected, skills directory missing — run `bb skills install --all`✓ Last sync 2m ago — 0 pending sessions
bb stores per-repo settings in .buildbetter/ at the repo root (it’s safe to commit). Use these to opt repos into different defaults — for example, a repo where sessions should never sync to the cloud.
bb config init # create .buildbetter/ in the current repobb config get <key> # read a settingbb config set <key> <value> # write a settingbb config list # show every setting (with where it comes from)
Common keys:
Key
Effect
sync.enabled
false keeps all sessions for this repo local-only
sessions.exclude_branches
Glob list of branches that should never be indexed (e.g. secret/*)
Most commands support --json for machine-readable output, which makes bb easy to wire into pre-commit hooks, PR templates, or CI:
# Print the most recent session ID for the current branch as JSONbb agent-sessions list --branch "$(git branch --show-current)" --since 1d --json \ | jq -r '.[0].id'# Fail a pre-commit hook if there's no session attached to this branchtest -n "$(bb agent-sessions list --branch HEAD --json | jq '.[0]')" \ || { echo "No agent session linked — run bb agent-sessions link"; exit 1; }
Exit codes are stable: 0 success, 1 user error, 2 not signed in, 3 network failure, 4 integrity / corrupted state.
